SparseFillEmptyRows
====================



对稀疏张量按行进行补全操作。当某一行在输入稀疏表示中不存在非零元素时，
使用给定的 **default_value** 为该行补充一个元素，并生成新的稀疏表示结果。
同时可选地输出反向索引映射关系。

该算子常用于保证稀疏张量在行维度上的完备性。

.. math::

    \text{if row } r \text{ is empty:} \quad
    (r, 0, \dots) \rightarrow default\_value

输入：
    - **N** - 输入稀疏元素个数。
    - **rank** - 稀疏张量的秩（索引维度）。
    - **dense_rows** - 稠密行数。
    - **indices_ptr** - 输入稀疏索引数组地址，大小为 ``N × rank``。
    - **values_ptr** - 输入稀疏值数组地址。
    - **default_value** - 用于填充空行的默认值。
    - **scratch_ptr** - 中间缓冲区，用于存放前缀和信息。
    - **output_reverse_index_map_ptr** - 反向索引映射输出地址（可为 NULL）。
    - **core_mask** - 核掩码（仅共享存储版本需要）。

输出：
    - **output_y_indices_ptr** - 输出稀疏索引数组地址。
    - **output_y_values_ptr** - 输出稀疏值数组地址。
    - **filled_count** - 每一行填充计数结果。

支持平台：
    ``FT78NE``
    ``MT7004``

.. note::
    - FT78NE 支持fp, dp, int8, int16, int32, cplx64, cplx128
    - MT7004 支持hp, fp, int16, int32, cplx64

**共享存储版本:**

.. c:function:: void i8_sparsefillemptyrows_s(int N, int rank, int dense_rows, int *indices_ptr, int8_t *values_ptr, int8_t default_value, int *scratch_ptr, int *output_y_indices_ptr, int8_t *output_y_values_ptr, int *output_reverse_index_map_ptr, int *filled_count, int core_mask)
.. c:function:: void i16_sparsefillemptyrows_s(int N, int rank, int dense_rows, int *indices_ptr, int16_t *values_ptr, int16_t default_value, int *scratch_ptr, int *output_y_indices_ptr, int16_t *output_y_values_ptr, int *output_reverse_index_map_ptr, int *filled_count, int core_mask)
.. c:function:: void i32_sparsefillemptyrows_s(int N, int rank, int dense_rows, int *indices_ptr, int32_t *values_ptr, int32_t default_value, int *scratch_ptr, int *output_y_indices_ptr, int32_t *output_y_values_ptr, int *output_reverse_index_map_ptr, int *filled_count, int core_mask)
.. c:function:: void hp_sparsefillemptyrows_s(int N, int rank, int dense_rows, int *indices_ptr, half *values_ptr, half default_value, int *scratch_ptr, int *output_y_indices_ptr, half *output_y_values_ptr, int *output_reverse_index_map_ptr, int *filled_count, int core_mask)
.. c:function:: void fp_sparsefillemptyrows_s(int N, int rank, int dense_rows, int *indices_ptr, float *values_ptr, float default_value, int *scratch_ptr, int *output_y_indices_ptr, float *output_y_values_ptr, int *output_reverse_index_map_ptr, int *filled_count, int core_mask)
.. c:function:: void dp_sparsefillemptyrows_s(int N, int rank, int dense_rows, int *indices_ptr, double *values_ptr, double default_value, int *scratch_ptr, int *output_y_indices_ptr, double *output_y_values_ptr, int *output_reverse_index_map_ptr, int *filled_count, int core_mask)
.. c:function:: void c64_sparsefillemptyrows_s(int N, int rank, int dense_rows, int *indices_ptr, float *values_ptr, float default_value, int *scratch_ptr, int *output_y_indices_ptr, float *output_y_values_ptr, int *output_reverse_index_map_ptr, int *filled_count, int core_mask)
.. c:function:: void c128_sparsefillemptyrows_s(int N, int rank, int dense_rows, int *indices_ptr, double *values_ptr, double default_value, int *scratch_ptr, int *output_y_indices_ptr, double *output_y_values_ptr, int *output_reverse_index_map_ptr, int *filled_count, int core_mask)

**C调用示例：**

.. code-block:: c
    :linenos:
    :emphasize-lines: 17-21

    //FT78NE示例
    #include <stdio.h>
    #include <sparsefillemptyrows.h>

    int main(int argc, char* argv[]) {
        int N = 4, rank = 2, dense_rows = 6;
        int *indices = (int *)0xA0000000;
        float *values = (float *)0xA0010000;
        float default_value = 0.0f;
        int *scratch = (int *)0xA0020000;
        int *out_indices = (int *)0xC0000000;
        float *out_values = (float *)0xC0010000;
        int *reverse_map = (int *)0xC0020000;
        int *filled_count = (int *)0xC0030000;
        int core_mask = 0xff;

        fp_sparsefillemptyrows_s(
            N, rank, dense_rows,
            indices, values, default_value,
            scratch, out_indices, out_values,
            reverse_map, filled_count, core_mask);

        return 0;
    }


**私有存储版本:**

.. c:function:: void i8_sparsefillemptyrows_p(int N, int rank, int dense_rows, int *indices_ptr, int8_t *values_ptr, int8_t default_value, int *scratch_ptr, int *output_y_indices_ptr, int8_t *output_y_values_ptr, int *output_reverse_index_map_ptr, int *filled_count)
.. c:function:: void i16_sparsefillemptyrows_p(int N, int rank, int dense_rows, int *indices_ptr, int16_t *values_ptr, int16_t default_value, int *scratch_ptr, int *output_y_indices_ptr, int16_t *output_y_values_ptr, int *output_reverse_index_map_ptr, int *filled_count)
.. c:function:: void i32_sparsefillemptyrows_p(int N, int rank, int dense_rows, int *indices_ptr, int32_t *values_ptr, int32_t default_value, int *scratch_ptr, int *output_y_indices_ptr, int32_t *output_y_values_ptr, int *output_reverse_index_map_ptr, int *filled_count)
.. c:function:: void hp_sparsefillemptyrows_p(int N, int rank, int dense_rows, int *indices_ptr, half *values_ptr, half default_value, int *scratch_ptr, int *output_y_indices_ptr, half *output_y_values_ptr, int *output_reverse_index_map_ptr, int *filled_count)
.. c:function:: void fp_sparsefillemptyrows_p(int N, int rank, int dense_rows, int *indices_ptr, float *values_ptr, float default_value, int *scratch_ptr, int *output_y_indices_ptr, float *output_y_values_ptr, int *output_reverse_index_map_ptr, int *filled_count)
.. c:function:: void dp_sparsefillemptyrows_p(int N, int rank, int dense_rows, int *indices_ptr, double *values_ptr, double default_value, int *scratch_ptr, int *output_y_indices_ptr, double *output_y_values_ptr, int *output_reverse_index_map_ptr, int *filled_count)
.. c:function:: void c64_sparsefillemptyrows_p(int N, int rank, int dense_rows, int *indices_ptr, float *values_ptr, float default_value, int *scratch_ptr, int *output_y_indices_ptr, float *output_y_values_ptr, int *output_reverse_index_map_ptr, int *filled_count)
.. c:function:: void c128_sparsefillemptyrows_p(int N, int rank, int dense_rows, int *indices_ptr, double *values_ptr, double default_value, int *scratch_ptr, int *output_y_indices_ptr, double *output_y_values_ptr, int *output_reverse_index_map_ptr, int *filled_count)

**C调用示例：**

.. code-block:: c
    :linenos:
    :emphasize-lines: 15-19

    //FT78NE示例
    #include <stdio.h>
    #include <sparsefillemptyrows.h>

    int main(int argc, char* argv[]) {
        int N = 4, rank = 2, dense_rows = 6;
        int *indices = (int *)0x10810000;
        float *values = (float *)0x10820000;
        float default_value = 0.0f;
        int *scratch = (int *)0x10830000;
        int *out_indices = (int *)0x10840000;
        float *out_values = (float *)0x10850000;
        int *filled_count = (int *)0x10860000;

        fp_sparsefillemptyrows_p(
            N, rank, dense_rows,
            indices, values, default_value,
            scratch, out_indices, out_values,
            NULL, filled_count);

        return 0;
    }